home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / clang / c_dates.zip / CDATES.DOC < prev    next >
Text File  |  1987-08-04  |  8KB  |  173 lines
  1.     - Hi there -
  2.  
  3.          Finally, there is a quick and easy way to manipulate dates in
  4.     the "C" programming  language;  that  is  what this package is all
  5.     about.
  6.  
  7.          The "C"  programming language  is,  in  this  authors  humble
  8.     opinion, the best programming language ever invented by man. Among
  9.     its weaker points,  however, is its inability ( at  least  in  its
  10.     most basic form ) to handle any sort of date variable.  This is an
  11.     important capability in  most  business  applications, which still
  12.     constitutes the majority of the programming effort in America, and
  13.     yet there hasn't been ( until now  )  an acceptable way of dealing
  14.     with this problem.  This has always struck me as  somewhat  of  an
  15.     injustice to the power of "C", so I decided to write a library for
  16.     the general public that would "do the trick".
  17.  
  18.          Manipulating dates in an effective manner involves converting
  19.     what we normally  think  of  as a "date" into a single number that
  20.     represents the number of days since  some arbitrary point in time.
  21.     For these routines, that arbitrary point in time is simply January
  22.     0, year 0000.   January  2nd,  year  0000, for example,  would  be
  23.     represented as the number 2, January 3rd, year 0000, as the number
  24.     3, and so  on.  Once the conversion is performed, calculating such
  25.     things as the day of the week, or  the  number of days between two
  26.     dates, becomes possible.
  27.  
  28.          This numerical  representation  of  a  date   is  called  the
  29.     "julian" representation, and  the  proper  name  of the equivalent
  30.     colloquial date, ie: one expressed  in terms of the month, day and
  31.     year, is called the "gregorian" representation.   These  names are
  32.     worth remembering, as  the documentation in this package refers to
  33.     all dates as either one or the other.
  34.  
  35.          All of the routines in this  library,  with  the exception of
  36.     the actual conversion  routines  themselves, manipulate  only  the
  37.     julian form of the date, the idea being that to manipulate a date,
  38.     the user first  converts  it  to  a  number, performs the required
  39.     calculations, then converts it back  to the readable ( gregorian )
  40.     form.
  41.  
  42.          There are only nine functions in this library, three of which
  43.     are implemented as rather trivial macros.  With these  nine, it is
  44.     hoped that the  user  can  accomplish  almost  any  kind  of  date
  45.     calculation required.  The names  and a brief description of these
  46.     functions are as follows:
  47.  
  48.     compiled functions:
  49.     ======== =========
  50.  
  51.     gtoj    -  to convert gregorian dates to julian dates
  52.     jtog    -  to convert julian dates to gregorian dates
  53.     dow     -  to find the numerical day of the week from a julian
  54.                date
  55.     fulldte -  to express a julian date as a verbose gregorian date
  56.     daycnt  -  to compute the days between two dates, with or without
  57.                weekends
  58.     newdate -  to compute a new date by adding or subtracting
  59.                weekdays, weekends, or both
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.     macro functions:
  68.     ===== =========
  69.  
  70.     suncnt  -  to  compute the number of Sundays occurring between two
  71.                julian dates
  72.     satcnt  -  to compute the number  of  Saturdays  occurring between
  73.                two julian dates
  74.     wkend   -  to  find the week-ending date ( ie:  the  date  of  the
  75.                following Saturday ) for a given julian date
  76.  
  77.          I have not included any of the fancier stuff, such as perhaps
  78.     a macro that  calculates  the  date for Thanksgiving for any given
  79.     year, for that,  I think, is best  left  up  to  the  user  as  an
  80.     exercise.
  81.  
  82.          For a  full  description  of  each  of  the   above  compiled
  83.     functions, please refer  to  the  source  file, "C_dATES.C", where
  84.     each particular module's code is  prefaced  by  a  collection of C
  85.     comment lines containing the associated usage summary.
  86.  
  87.          The macro  functions  are  documented  at  the  end  of  this
  88.     document, in what I have called "Appendix A".
  89.  
  90.          These routines   can   handle   any   date,   regardless   of
  91.     chronological magnitude, from January  1st,  year 0000 to December
  92.     31st, 9999, and the source ( included ) for these  routines can be
  93.     re-compiled using any  ANSI  C compiler, on virtually any machine.
  94.     The jtog and fulldte functions,  however,  assume  an  ASCII based
  95.     machine, but the  source can easily be modified to  employ  almost
  96.     any type of character set ( with maybe a little forethought... ).
  97.  
  98.          The actual  object  module library that is included with this
  99.     package, "C_dATES.LIB", was  created   using   the   Microsoft   C
  100.     compiler, version 4.0.  There is no particular reason for choosing
  101.     this particular implementation, other than the fact that it is the
  102.     one that I use all the time.  ( It is actually quite good )
  103.  
  104.          With this package I have also included two example  programs,
  105.     written in MSC  v 4.0, that employ most of the functions contained
  106.     in this library, so that the user  can  get a feel for some of the
  107.     practical applications of these functions.  The name  of the first
  108.     program is "DAYS.EXE",  and  all  it  does, really, is compute the
  109.     days that exist between the two dates  input  on the command line.
  110.     The second program,  called "NDATE.EXE", simply returns a new date
  111.     that is computed using a start date and adding a number of days of
  112.     a specified type.   For  an  more  detailed  explanation  of their
  113.     usage, simply type in their respective names with no parameters.
  114.  
  115.          Should  you   have  any  questions,   comments,  suggestions,
  116.     contributions, expletives, marriage proposals, or hate mail, I can
  117.     be reached at my home address, 2841 Clydedale, apt  #345,  Dallas,
  118.     TX 75220, (  via  U.S.  mail!  ) or alternatively, you can leave a
  119.     message for me  at one or more of  the  following  (  excellent  )
  120.     public BBS's:
  121.  
  122.          IMPEESA'S PATH             (214) 699-0234   2400-N-8-1
  123.          SUPERCOMPUTER              (214) 270-6755   1200-N-8-1
  124.          INSIDE TRACK               (214) 422-4772   2400-N-8-1
  125.  
  126.          You will need to know my name;  it's James Seed...
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.                             A P P E N D I X   A
  134.                             ===================
  135.  
  136.                          - Macro Function Usage -
  137.                            ====================
  138.  
  139.  
  140.     suncnt( julian1, julian2 )  -  this function returns the number of
  141.                                    Sundays that  exist between the two
  142.                                    julian  dates input, expressed as a
  143.                                    signed long  integer.    The  input
  144.                                    types are as follows:
  145.  
  146.                                    julian1  -   unsigned  long integer
  147.                                                julian date
  148.                                    julian2   -   unsigned long integer
  149.                                                julian date
  150.  
  151.     satcnt( julian1, julian2 )  -  this function returns the number of
  152.                                    Saturdays that  exist  between  the
  153.                                    two julian  dates  input, expressed
  154.                                     as  a  signed  long  integer.  The
  155.                                    input types are as follows:
  156.  
  157.                                    julian1  -  unsigned  long  integer
  158.                                                julian date
  159.                                    julian2  -   unsigned  long integer
  160.                                                julian date
  161.  
  162.     wkend( julian )   -  this function  finds  the  week-ending  date,
  163.                         expressed as an unsigned long  integer  julian
  164.                         Saturday, that   represents   the   week  that
  165.                         includes the unsigned long julian date input.
  166.  
  167.  
  168.  
  169.     *** IMPORTANT NOTE ***
  170.  
  171.     The author assumes  no  responsibility  for  any  loss  or  damage
  172.     arising out of the use, misuse, or inability to use this product.
  173.